# React

In this document, you will learn how to build a React component library with Rslib. You can check out React related example projects in [Examples](https://github.com/rspack-contrib/rstack-examples/tree/main/rslib).

## Create React project

You can use `create-rslib` to create a project with Rslib + React. Just execute the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
    npm: 'npm create rslib@latest',
    yarn: 'yarn create rslib',
    pnpm: 'pnpm create rslib@latest',
    bun: 'bun create rslib@latest',
  }}
/>

Then select `React` when prompted to "Select template".

## Use Rslib in an existing project

To develop a React library, you need to set the [target](/config/rsbuild/output#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild.

To compile React (JSX and TSX), you need to register the Rsbuild [React Plugin](https://rsbuild.rs/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds.

For example, register in `rslib.config.ts`:

```ts title="rslib.config.ts" twoslash
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react'; // [!code highlight]

export default defineConfig({
  lib: [
    // ...
  ],
  // [!code highlight:4]
  output: {
    target: 'web',
  },
  plugins: [pluginReact(/** options here */)],
});
```

## JSX transform

- **Type:** `'automatic' | 'classic' | 'preserve'`
- **Default:** `'automatic'`

React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in version 17. This new transform removes the need to import `React` when using JSX.

By default, Rslib uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher and the `peerDependencies` should be specified as `"react": ">=16.14.0"`.

To change the JSX transform, you can set the [swcReactOptions](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime) option in `@rsbuild/plugin-react`.

For example, to use the classic runtime:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        runtime: 'classic',
      },
    }),
  ],
});
```

When you need to keep native JSX in the build output, you can set the runtime to `'preserve'` to leave JSX syntax unchanged without transforming it, which is useful for subsequent processing by other bundlers.

::: warning

When using `runtime: 'preserve'`, you must set `bundle: false` to enable [bundleless mode](/guide/basic/output-structure#bundle--bundleless) to keep files unbundled.

:::

To emit `.jsx` files, you can configure the JS filename template through [output.filename](/config/rsbuild/output#outputfilename) option:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      bundle: false,
      format: 'esm',
      // [!code highlight:5]
      output: {
        filename: {
          js: '[name].jsx',
        },
      },
    },
  ],
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'preserve',
      },
    }),
  ],
});
```

## JSX import source

- **Type**: `string`
- **Default**: `'react'`

When `runtime` is set to `'automatic'`, you can specify the import path of the JSX transform through `importSource`.

For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        importSource: '@emotion/react',
      },
    }),
  ],
});
```

## SVGR

Read [Import SVGR](/guide/advanced/svgr-files) for more details.

## Further reading

- [Rsbuild React Plugin](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime)
- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact)
